feat: pin func-utils image to a per-release-branch tag by gauron99 · Pull Request #3994 · knative/func

gauron99 · 2026-08-06T20:56:59Z

Changes

🎁 Pin the func-utils image per minor release

Every released CLI embeds ghcr.io/knative/func-utils:v2, and main re-publishes v2 on every green push. So changes on main reach the cluster side of old CLIs: v1.20 runs scaffold <path>, but v2 needs two arguments since #3237.

Main now embeds the image of the minor in development, func-utils:1.24, and its green pushes publish that tag. A release-X.Y branch cut from main already embeds func-utils:X.Y, and the image exists, so the release can go out right after the cut.

version.FuncUtilsImage in pkg/version/version.go holds the reference. The three variables func reads default to it, so plain go build and library users get it too. FUNC_UTILS_IMG and -X ldflags still override it. make func-utils-image prints what a build embeds.
functions.yaml publishes the tag the source embeds, from main and from release-*. A release branch must embed its own minor. Once release-X.Y exists, main skips the publish (except for the cut commit) until it moves to the next minor, so main never overwrites X.Y.
New update-func-utils-image.yaml: cutting release-X.Y opens a PR that moves main to X.(Y+1). A maintainer has to start that PR's CI, because events made with github.token start no workflows.
hack/release.sh refuses a vX.Y.Z release unless the build embeds func-utils:X.Y and that image exists.
docs/func-utils-image.md describes the tags and the release cut.

For reviewers

Nothing publishes v2 any more, so CLIs up to 1.23 keep the image as of this merge.
This must merge, and main must publish :1.24, before release-1.24 is cut (knative 1.24 is due 2026-10-27).
The workflow changes have not run on GitHub yet. The first push to main after the merge should publish ghcr.io/knative/func-utils:1.24.

/kind enhancement

Release Note

func now runs ghcr.io/knative/func-utils:<minor> (for example 1.24) in the cluster instead of the floating v2 tag, so on-cluster builds and deploys no longer change under a released CLI. If you mirror images, mirror the new tag.

Docs

🤖 Generated with Claude Code

knative-prow · 2026-08-06T20:57:02Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

gauron99 · 2026-08-21T13:20:46Z

@matejvasek @lkingland WDYT?

Copilot

🟡 Changes recommended

The current release-branch detection in the Makefile can fall back to v2 in detached-HEAD CI checkouts, undermining the intended per-branch pinning behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR makes func embed a more stable func-utils image tag per release branch/minor version to avoid older released CLIs being broken by changes published under a floating tag.

Changes:

Derive FUNC_UTILS_IMG from either an exact release KVER or a release-X.Y branch, otherwise defaulting to v2.
Align local e2e image publishing (hack/images.sh) with the embedded image tag via a new make func-utils-image helper.
Update docs and CI so func-utils images are published as v2 on main and X.Y on release-X.Y branches.

File summaries

File	Description
Makefile	Derives and embeds a per-release-branch/per-minor `func-utils` image tag; adds `func-utils-image` helper target.
hack/images.sh	Publishes locally built `func-utils` images using the same tag embedded into the built `func` binary.
docs/README.md	Adds documentation link for the `func-utils` image policy.
docs/func-utils-image.md	Documents tag scheme and compatibility policy for `func-utils`.
.github/workflows/functions.yaml	Publishes `func-utils` as `v2` on `main` and `X.Y` on `release-X.Y`, including manual dispatch support.

Review details

Files reviewed: 5/5 changed files
Comments generated: 1
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

matejvasek · 2026-09-01T20:02:29Z

Automated Code Review

🤖 This review was generated by Claude Code (AI). Treat findings as suggestions to verify, not verdicts.

This PR pins the func-utils image to a per-release-branch tag. It's well-constructed — the findings below are mostly low-severity robustness/consistency issues.

Findings

1. Broad release-branch gate vs. strict tag regex — .github/workflows/functions.yaml
The job-level if accepts any refs/heads/release-* ref, but the "Derive Image Tag" step only accepts ^release-([0-9]+\.[0-9]+)$ and exit 1s otherwise. A push to release-1.24.0, release-v1.24, or release-next passes the gate, runs the full build + e2e, then hard-fails at derive — turning the workflow red instead of cleanly skipping.

2. Detached-HEAD fallback yields floating v2 — Makefile
Release-tag pinning falls back to git branch --show-current, which is empty in detached-HEAD checkouts (git worktree, SHA checkout, Prow's non-TAG_RELEASE path). This silently embeds ghcr.io/knative/func-utils:v2 into a release-branch binary, defeating the pin. Official releases are safe only because release.sh passes an exact KVER.

3. workflow_dispatch republishes utils but skips CLI image — .github/workflows/functions.yaml
publish-image (ko func CLI image) gates on push && main only, while build and publish-utils-image also allow workflow_dispatch. A manual dispatch on main republishes the utils image but silently skips the CLI image.

4. FUNC_UTILS_IMG repo-path override breaks mirror mapping — hack/images.sh
images.sh reuses only the tag from make func-utils-image and hardcodes registry.localtest.me/knative/func-utils. A FUNC_UTILS_IMG override that changes the repo/registry path (the documented "always wins" override) makes the binary embed one path while images.sh pushes to another — in-cluster e2e pulls fail to resolve.

5. Scope creep: deleted "Fork CI note" — .github/workflows/functions.yaml
The PR removes the unrelated comment documenting why codecov no-ops on forks (Hamr#395 / Functions#57). Rationale is lost and unrelated to the func-utils pin.

6. Redundant if duplicated from needs — .github/workflows/functions.yaml
publish-utils-image's new if duplicates the identical condition on build, which it already declares in needs. When build skips, the job skips via needs anyway. Two copies to keep in sync.

7. Inaccurate KVER comment — Makefile
The comment says Prow passes KVER as v1.24.0, but hack/release.sh passes KVER="${TAG}" (the knative-vX.Y.Z form). No functional impact — the regex tolerates both — but the comment could mislead.

Highest-value items: #1 (workflow fails red instead of skipping) and #2 (pin silently defeated in detached-HEAD builds).

gauron99 · 2026-10-20T04:24:38Z

/retest

Copilot

🔵 Needs a closer look

Cross-branch publication has an unresolved race, and the release-cut workflows still require validation on GitHub.

1 open issue

Serialize image publications across branches to prevent overwrites · New

1 resolved since last review

The release-branch pinning path relies on git branch --show-current, which returns an empty…

_{Review effort: Balanced}

aliok · 2026-10-22T09:48:16Z

/lgtm
/approve
/hold

I haven't seen anything other than the things stated above.

Every released CLI embeds ghcr.io/knative/func-utils:v2, which main re-publishes on every green push, so changes on main reach the cluster side of old CLIs. For example v1.20 runs "scaffold <path>", but v2 needs two arguments since knative#3237. Main now carries the image of the minor in development: it embeds func-utils:1.24, and its green pushes publish that tag. A release-X.Y branch cut from main already embeds func-utils:X.Y, and the image exists, so the cut needs no change and the release can go at once. - The reference lives in one constant, version.FuncUtilsImage. The three variables func reads default to it, so plain go build and source tarballs embed it too. FUNC_UTILS_IMG and -X ldflags still override it. make func-utils-image prints what a build embeds; the workflows, hack/images.sh and hack/release.sh read it from there. - The Functions workflow publishes the tag the source embeds, from main and from release branches. A release branch must embed its own minor. Once release-X.Y is cut, main skips the publish until it moves to the next minor, unless its commit is the branch head (the cut commit's own run), so main never overwrites X.Y. - Cutting release-X.Y runs the new workflow update-func-utils-image.yaml, which opens a PR that moves main to X.(Y+1). - hack/release.sh refuses a vX.Y.Z release unless the build embeds func-utils:X.Y and that image exists. - Nothing publishes v2 any more, so CLIs up to 1.23 keep the image as of this change. - docs/func-utils-image.md describes the tags, the compatibility rule and the release cut.

gauron99 · 2026-10-22T13:50:37Z

Ive fixed Matej's point 4, here's AI summary:

🤖 The design changed after these reviews. The PR description has the details. In short:

main embeds the image of the minor in development (ghcr.io/knative/func-utils:1.24, in version.FuncUtilsImage) and publishes it on every green push.
Cutting release-X.Y needs no change. The new workflow update-func-utils-image.yaml opens a PR that moves main to X.(Y+1). Until it merges, main doesn't publish (except for the cut commit itself).
v2 is frozen, so CLIs up to 1.23 keep the image as of this merge.
This has to merge, and main has to publish :1.24, before release-1.24 is cut on 2026-10-27.

@matejvasek @lkingland could you take another look?

Answers to @matejvasek's review:

Broad gate vs strict regex: still true. A release-foo push runs CI, then "Derive Image Tag" fails and nothing publishes. All 23 release branches in knative/func are release-N.N, so we keep release-* like every other workflow.
Fallback to v2 when CI checks out a commit instead of a branch: gone. Nothing reads the branch now; the image is a constant in pkg/version/version.go.
workflow_dispatch publishes utils but not the CLI image: gone. A manual run publishes neither, because build runs only on push.
images.sh drops the repo path of FUNC_UTILS_IMG: fixed. It now keeps the full path and only swaps the registry host.
Deleted "Fork CI note": no longer in the diff.
Repeated if on publish-utils-image: gone. The job only has needs: build.
Wrong KVER comment: gone. The Makefile no longer derives the tag from KVER.

aliok · 2026-10-23T07:10:53Z

/lgtm
/approve

LGTM'ing this one as I believe it has matured enough, but keeping the hold to leave the merging to you/others.

Copilot

🟡 Changes recommended

A critical release-tag parsing defect blocks v1 releases and must be fixed before approval.

1 open issue

Strip knative- prefix before parsing v1 release tags · New

1 resolved since last review

Serialize image publications across branches to prevent overwrites

_{Review effort: Lite}

knative-prow · 2026-10-27T21:57:12Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: aliok, gauron99, lkingland

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [aliok,gauron99,lkingland]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

gauron99 · 2026-10-28T10:19:35Z

/hold cancel

knative-prow Bot added do-not-merge/work-in-progress 🤖 PR should not merge because it is a work in progress. approved 🤖 PR has been approved by an approver from all required OWNERS files. labels Aug 6, 2026

knative-prow Bot requested review from dsimansk and jrangelramos August 6, 2026 20:57

knative-prow Bot added the size/L 🤖 PR changes 100-499 lines, ignoring generated files. label Aug 6, 2026

gauron99 requested review from lkingland and matejvasek and removed request for dsimansk and jrangelramos August 30, 2026 19:08

lkingland approved these changes Aug 31, 2026

View reviewed changes

knative-prow Bot assigned lkingland Aug 31, 2026

knative-prow Bot added the lgtm 🤖 PR is ready to be merged. label Aug 31, 2026

matejvasek requested a lite review from Copilot September 1, 2026 19:50

Copilot started reviewing on behalf of matejvasek September 1, 2026 19:51

View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread Makefile Outdated

gauron99 force-pushed the pin-func-utils-per-release branch from 798b48b to a1fc796 Compare October 19, 2026 20:55

knative-prow Bot removed the lgtm 🤖 PR is ready to be merged. label Oct 19, 2026

gauron99 force-pushed the pin-func-utils-per-release branch from a1fc796 to bc315d1 Compare October 19, 2026 21:05

gauron99 marked this pull request as ready for review October 19, 2026 21:05

knative-prow Bot removed the do-not-merge/work-in-progress 🤖 PR should not merge because it is a work in progress. label Oct 19, 2026

knative-prow Bot requested review from dsimansk and jrangelramos October 19, 2026 21:05

gauron99 requested a balanced review from Copilot October 20, 2026 06:59

Copilot started reviewing on behalf of gauron99 October 20, 2026 06:59

View session

Copilot AI reviewed Oct 20, 2026

View reviewed changes

Comment thread .github/workflows/functions.yaml

knative-prow Bot added the do-not-merge/hold 🤖 PR should not merge because someone has issued a /hold command. label Oct 22, 2026

knative-prow Bot assigned aliok Oct 22, 2026

knative-prow Bot added the lgtm 🤖 PR is ready to be merged. label Oct 22, 2026

gauron99 force-pushed the pin-func-utils-per-release branch from bc315d1 to 7249110 Compare October 22, 2026 13:49

knative-prow Bot removed the lgtm 🤖 PR is ready to be merged. label Oct 22, 2026

aliok requested a lite review from Copilot October 23, 2026 07:10

Copilot started reviewing on behalf of aliok October 23, 2026 07:10

View session

knative-prow Bot added the lgtm 🤖 PR is ready to be merged. label Oct 23, 2026

Copilot AI reviewed Oct 23, 2026

View reviewed changes

Comment thread hack/release.sh

lkingland approved these changes Oct 27, 2026

View reviewed changes

knative-prow Bot removed the do-not-merge/hold 🤖 PR should not merge because someone has issued a /hold command. label Oct 28, 2026

knative-prow Bot merged commit b0ba914 into knative:main Oct 28, 2026
73 of 74 checks passed

Conversation

gauron99 commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

knative-prow Bot commented Aug 6, 2026

Uh oh!

gauron99 commented Aug 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

matejvasek commented Sep 1, 2026

Automated Code Review

Findings

Uh oh!

gauron99 commented Oct 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Uh oh!

aliok commented Oct 22, 2026

Uh oh!

gauron99 commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aliok commented Oct 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

knative-prow Bot commented Oct 27, 2026

Uh oh!

gauron99 commented Oct 28, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gauron99 commented Aug 6, 2026 •

edited

Loading

gauron99 commented Oct 22, 2026 •

edited

Loading